{
 "metadata": {
  "name": "Blowout_sim"
 }, 
 "nbformat": 2, 
 "worksheets": [
  {
   "cells": [
    {
     "cell_type": "markdown", 
     "source": [
      "<h3>Submarine Accidental Oil Spill Simulator"
     ]
    }, 
    {
     "cell_type": "markdown", 
     "source": [
      "This notebook provides a user interface to the Texas A&M Oil Spill Calculator (``TAMOC``) simulation", 
      "modules for simulating an accidental subsea oil spill.  Additional example scripts are distributed", 
      "with the ``TAMOC`` software in the ``./bin`` directory.  These scripts are a good starting place for ", 
      "developing simulation scripts that can iterate through several blowout scenarios automatically.  This ", 
      "notebook provides a simple means to define a single spill case, run the simulation and save the results ", 
      "to the hard disk."
     ]
    }, 
    {
     "cell_type": "code", 
     "collapsed": true, 
     "input": [
      "from tamoc import ambient", 
      "from tamoc import dbm", 
      "from tamoc import stratified_plume_model"
     ], 
     "language": "python", 
     "outputs": [], 
     "prompt_number": 1
    }, 
    {
     "cell_type": "markdown", 
     "source": [
      "<h4>Ambient CTD Data"
     ]
    }, 
    {
     "cell_type": "markdown", 
     "source": [
      "The first step in any spill simulation is to define the ambient CTD data.  The ``TAMOC`` module ", 
      "`ambient.py` provides the tools needed to read in CTD data from text files and organize it into the ", 
      "netCDF files used by the ``TAMOC`` simulation modules.  Examples of how to do this are provided in ", 
      "the `./bin/ambient` directory of the ``TAMOC`` distribution.  Here, we use the CTD data created by", 
      "the ``TAMOC`` test files and stored in the `./test/output` directory.  Please be sure that all of ", 
      "the unit tests have passed by running:", 
      "", 
      "     py.test -v", 
      "", 
      "from the command prompt within the ``TAMOC`` distribution directory.  This will create the necessary ", 
      "netCDF datasets used in this Notebook.  You may also edit this notebook to point to netCDF datasets", 
      "that have been created elsewhere.  "
     ]
    }, 
    {
     "cell_type": "code", 
     "collapsed": true, 
     "input": [
      "# Enter the dataset name and relative path from this directory to the CTD dataset", 
      "ctd_file = '../test/output/test_BM54.nc'"
     ], 
     "language": "python", 
     "outputs": [], 
     "prompt_number": 2
    }, 
    {
     "cell_type": "code", 
     "collapsed": true, 
     "input": [
      "# Initialize the stratified plume model with this CTD dataset", 
      "ctd = ambient.Profile(ctd_file, chem_names='all')", 
      "spm = stratified_plume_model.Model(ctd)", 
      "disp_phases = []"
     ], 
     "language": "python", 
     "outputs": [], 
     "prompt_number": 3
    }, 
    {
     "cell_type": "markdown", 
     "source": [
      "<h4>Define the Release Conditions"
     ]
    }, 
    {
     "cell_type": "markdown", 
     "source": [
      "The release conditions are defined by the release depth (m), the effective circular radius of the release", 
      "port (m), and the temperature of the released fluids (K)."
     ]
    }, 
    {
     "cell_type": "code", 
     "collapsed": true, 
     "input": [
      "# Enter the release conditions", 
      "z0 = 1000.   ", 
      "R = 0.15", 
      "T0 = 273.15 + 35."
     ], 
     "language": "python", 
     "outputs": [], 
     "prompt_number": 4
    }, 
    {
     "cell_type": "markdown", 
     "source": [
      "<h4>Define the Gas Phase Bubbles"
     ]
    }, 
    {
     "cell_type": "markdown", 
     "source": [
      "This model allows the user to specify an arbitrary number of gas and liquid phase fluid particles, each ", 
      "with a different mass flux and initial diameter.  The first step is to create a fluid particle object", 
      "with the composition information and equations of state; this is done using the `dbm.py` module.  Examples ", 
      "of how to work with this module are provided in `./bin/dbm`.  The names of the components of the ", 
      "mixture must match the key words in the `./tamoc/data/ChemData.csv` file.  If new chemical names are ", 
      "needed, they should first be added to that database."
     ]
    }, 
    {
     "cell_type": "code", 
     "collapsed": true, 
     "input": [
      "# Enter the composition of the released gas at the release point", 
      "composition = ['methane', 'ethane', 'propane', 'oxygen']", 
      "mol_frac = [0.93, 0.05, 0.02, 0.0]"
     ], 
     "language": "python", 
     "outputs": [], 
     "prompt_number": 5
    }, 
    {
     "cell_type": "code", 
     "collapsed": true, 
     "input": [
      "# Initialize a DBM object for handling the gas phase", 
      "gas = dbm.FluidParticle(composition)"
     ], 
     "language": "python", 
     "outputs": [], 
     "prompt_number": 6
    }, 
    {
     "cell_type": "markdown", 
     "source": [
      "Gas bubbles are added to the simulation by putting `stratified_plume_model.Particle` objects into ", 
      "the `disp_phases` list.  This can be done any number of ways.  Here, we use the helper functions ", 
      "defined in `stratified_plume_model.particle_from_mb0` which initializes a `Particle` object based", 
      "on a given initial diameter (m) and total mass flux (kg/s) specified at the release.  In order to ", 
      "input a size distribution, multiple sizes can be specified as in the following."
     ]
    }, 
    {
     "cell_type": "code", 
     "collapsed": true, 
     "input": [
      "# Enter the gas bubble size distribution and mass fluxes associated with each size", 
      "de = np.array([0.04, 0.03, 0.02, 0.01, 0.0075, 0.005])", 
      "m0 = np.array([0.5, 1.5, 2.5, 3.5, 1.5, 0.5])", 
      "", 
      "# Enter the spreading ratio associated with each bubble size", 
      "lambda_1 = np.array([0.75, 0.8, 0.85, 0.9, 0.9, 0.95])"
     ], 
     "language": "python", 
     "outputs": [], 
     "prompt_number": 7
    }, 
    {
     "cell_type": "code", 
     "collapsed": true, 
     "input": [
      "# Append these particles to the disp_phases list", 
      "for i in range(len(de)):", 
      "    disp_phases.append(stratified_plume_model.particle_from_mb0(ctd, z0, gas, mol_frac, ", 
      "                                                                m0[i], de[i], lambda_1[i], ", 
      "                                                                T0))"
     ], 
     "language": "python", 
     "outputs": [], 
     "prompt_number": 8
    }, 
    {
     "cell_type": "markdown", 
     "source": [
      "<h4>Define the Liquid Phase Droplets"
     ]
    }, 
    {
     "cell_type": "markdown", 
     "source": [
      "Following the same procedure as for the gas but with different equations of state, liquid droplets", 
      "can be added to the simulation.  Start, by defining a new set of equations of state.  Here, we assume", 
      "a non-dissolving oil phase."
     ]
    }, 
    {
     "cell_type": "code", 
     "collapsed": true, 
     "input": [
      "# Enter the composition of the release liquid oil at the release point", 
      "composition = ['inert']", 
      "rho_o = 890.     # density in kg/m^3", 
      "gamma = 30.      # API gravity in deg API", 
      "beta = 0.0007    # thermal expansion coefficient in K^(-1)", 
      "co = 2.90075e-9  # isothermal compressibility coefficient in Pa^(-1)"
     ], 
     "language": "python", 
     "outputs": [], 
     "prompt_number": 9
    }, 
    {
     "cell_type": "code", 
     "collapsed": true, 
     "input": [
      "# Initialize a DBM object for handling the oil phase", 
      "oil = dbm.InsolubleParticle(True, True, rho_o, gamma, beta, co)"
     ], 
     "language": "python", 
     "outputs": [], 
     "prompt_number": 10
    }, 
    {
     "cell_type": "markdown", 
     "source": [
      "Oil droplets are added to the simulation in exactly the same way as for the gas bubbles above.  Here,", 
      "we demonstrate including several droplet sizes describing a prescribed size distribution."
     ]
    }, 
    {
     "cell_type": "code", 
     "collapsed": true, 
     "input": [
      "# Enter the oil droplet size distribution and mass fluxes associated with each size", 
      "de = np.array([0.02, 0.01, 0.0075, 0.005, 0.003])", 
      "m0 = np.array([1., 2.5, 5., 1., 0.5])", 
      "", 
      "# Enter the spreading ratio associated with each droplet size", 
      "lambda_1 = np.array([0.85, 0.90, 0.95, 0.95, 1.])"
     ], 
     "language": "python", 
     "outputs": [], 
     "prompt_number": 11
    }, 
    {
     "cell_type": "code", 
     "collapsed": true, 
     "input": [
      "# Append these particles to the disp_phases list", 
      "for i in range(len(de)):", 
      "    disp_phases.append(stratified_plume_model.particle_from_mb0(ctd, z0, oil, mol_frac, ", 
      "                                                                m0[i], de[i], lambda_1[i], ", 
      "                                                                T0))"
     ], 
     "language": "python", 
     "outputs": [], 
     "prompt_number": 12
    }, 
    {
     "cell_type": "markdown", 
     "source": [
      "<h4>Run the Simulation"
     ]
    }, 
    {
     "cell_type": "markdown", 
     "source": [
      "A few more parameters can be set to specify the way the simulation executes.  These include the ", 
      "maximum number of iterations allowed to seek convergence between the inner and outer plume solutions,", 
      "the relative error tolerance desired that defines acceptable convergence, and the maximum depth", 
      "step (m) to use in saving the model solution.  There are defined in the following."
     ]
    }, 
    {
     "cell_type": "code", 
     "collapsed": true, 
     "input": [
      "# Enter the simulation parameters", 
      "max_iterations = 15", 
      "err_tolerance = 0.2", 
      "output_dz_max = 10."
     ], 
     "language": "python", 
     "outputs": [], 
     "prompt_number": 13
    }, 
    {
     "cell_type": "code", 
     "collapsed": false, 
     "input": [
      "# Run the simulation", 
      "spm.simulate(disp_phases, z0, R, maxit=max_iterations, toler=err_tolerance, ", 
      "             delta_z = output_dz_max)"
     ], 
     "language": "python", 
     "outputs": [], 
     "prompt_number": 14
    }, 
    {
     "cell_type": "markdown", 
     "source": [
      "<h4>Save the Results"
     ]
    }, 
    {
     "cell_type": "markdown", 
     "source": [
      "The simulation results can be saved to a netCDF file, which can be used to continue analysis", 
      "within the ``TAMOC`` Python package, or an ascii text file for importing to another analysis", 
      "package, such as Excel or Matlab.  To save the data, specify a base output name with relative ", 
      "file path, a path to the CTD data, and a description of the CTD data."
     ]
    }, 
    {
     "cell_type": "code", 
     "collapsed": true, 
     "input": [
      "# Enter the information for saving the simulation", 
      "f_name = '../test/output/ntbk_blowout'", 
      "ctd_description = 'CTD data from Brooks McCall in file ./test/output/test_BM54.nc'"
     ], 
     "language": "python", 
     "outputs": []
    }, 
    {
     "cell_type": "code", 
     "collapsed": true, 
     "input": [
      "# Save a netCDF file for reuse by TAMOC", 
      "spm.save_sim(f_name + '.nc', ctd_file, ctd_description)", 
      "", 
      "# Save an ASCII text file for export to other programs", 
      "spm.save_txt(f_name + 'ASCII', ctd_file, ctd_description)"
     ], 
     "language": "python", 
     "outputs": []
    }, 
    {
     "cell_type": "code", 
     "collapsed": true, 
     "input": [], 
     "language": "python", 
     "outputs": []
    }
   ]
  }
 ]
}